Drag reorder settings
Description
Settings for defining the drag reorder behavior for the List control.
Discussion
The List Row Drag-to-Reorder action allows you to define settings that control the behavior of the action when Has row drag reorder behavior has been enabled. The action has two modes ("handle" and "downhold") that define how the user interacts with the List to reorder rows. For example, the List can be placed into reorder mode by pressing and holding on a List row, then dragging the row to its new position ("downhold" mode).
Alternatively, an icon can be placed in each row. The user then drags the icon to reorder rows ("handle" mode).
You can also define an event handler that fires when the user stops dragging a row or after moving the row to its desired position.
Row Drag-to-Reorder List Action Builder Properties
The following properties are used to configure the drag to reorder behavior. If you need more control over the behavior than is available through these properties,the Convert to low-level code can be used to convert the action to its underlying JSON, which is then added to the List using Advanced > Additional Settings property.
Mode
Specifies how the List-reorder action should work. There are two different modes for List row reordering:
- Downhold
User presses and holds the List row to move. This puts the List in reorder mode. User can the drag the row to the new location.
- Handle
The List is put into reorder mode when the user taps or clicks the drag handle. The drag handle can be an icon, a button, or other HTML. When the user drags the drag handle the row is moved to a new location in the List. If the user drags any other part of the row, the List is scrolled.
If Handle mode is used, you will need to add HTML to the List layout. Handle mode is typically used in a List with a freeform layout. See Adding a Drag Handle to the List Layout below for information on how to add the handle to the List's layout.
onMoveEnd Javascript
This action is fired when the user stop dragging on a List row to position the row at its new target location.
The JavaScript in this event can reference the following variables:
- lObj
A pointer to the List object.
- from
The zero based row number of the row the user is moving.
- to
The zero based row number of the target position for the row.
alert("Moving row " + from + " to row " + to + ".");Class name
One or more classes that will be applied to the row the user drags to a a new location.
Drop spot class name
One or more classes applied to the 'drop spot'. The 'drop spot' is the gap shown in the List layout where the row will be moved when the user releases the row.
Drag HTML Javascript
Your can replace the HTML that is shown for the row you are dragging. By default, the HTML in row you are dragging on is shown while you are dragging the row.
Your code can reference a variable called HTML, the HTML for the row you are dragging.
Your code must return the HTML to display. For example, the code below shows the HTML in the row you are dragging and adds a message ('Move to the target, then drop'):
html = html+'<div style="position: absolute; bottom: -26px; left: 0px; right: 0px; line-height: 26px; padding: 0px 6px; text-align: center; background: rgba(0,0,0,.75); color: #fff;">Move to the target, then drop</div>'
Adding a Drag Handle to the List Layout
The code below can be added to the List layout to add a drag handle. Javascript is also included that can be added to a button to toggle the display of the drag handle in the List control.
The following HTML markup for the drag handle icon can be added to the List freeform layout (recommended) template definition:
<div class="dragReorderHandle" a5-item="drag-reorder-handle">
<div>
<img src="svgIcon=#alpha-icon-bars:icon,24" />
</div>
</div>The following CSS is used to style the handle. This CSS can be added to the list via the CSS tab. The CSS tab provides quick access to the List builder's CSS tab.
.dragReorderHandle {
width: 0px;
overflow:hidden;
transition: width 300ms;
text-align:left;
white-space:nowrap;
float:left;
position:relative;
left: -6px;
cursor: move;
}
.dragReorderAllow .dragReorderHandle {
width: 40px;
}
.dragReorderAllow .dragReorderHandle div {
width: 40px;
}Javascript to show the drag handle in each row is shown below. This code adds the dragReorderAllow class name from the drag handle, causing it to be shown. It can be added to a button or link in a ControlBar or other control. Replace your-list-name with the name of the List that contains the drag behavior:
var lObj = {dialog.object}.getControl('your-list-name');
$acn(lObj.contId,'dragReorderAllow');Javascript to hide the drag handle in each row is shown below. This code removes the dragReorderAllow class name from the drag handle, causing it to be hidden. It can be added to a button or link in a ControlBar or other control. Replace your-list-name with the name of the List that contains the drag behavior:
var lObj = {dialog.object}.getControl('your-list-name');
$rcn(lObj.contId,'dragReorderAllow');How to Set the Drag-to-Reorder Mode at Run-time
The following JavaScript can be used to set the Drag-to-Reorder mode at run-time. This code can be added to a button's click event or any client-side event. It can also be returned from a server-side event:
var lObj = {dialog.object}.getControl('your-list-name');
lObj.__dragReorderSettings.type = 'handle'; //or 'downhold'
{dialog.object}._listRowDragReorderSetup(lObj);Videos
Row Drag Actions
A common user interface pattern seen in mobile apps that use a List is to allow the user to drag on a row in the List to invoke some type of action. For example in the iOS Email app a user can drag on a row to archive the row, mark is as unread/read, or move the row to another folder.
In this video we show how you can implementing row drag behavior an a List control.
See Also